home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Cream of the Crop 25
/
Cream of the Crop 25.iso
/
bbs
/
inf121d.zip
/
user.doc
< prev
Wrap
Text File
|
1996-11-09
|
87KB
|
1,982 lines
______ ___________________ ______
> |____________| InfoMail/386 1.20 |____________| <
~~||~~| Centurion |~~~~~~~~~~~~~~~~~~~| 2:2502/666 |~~||~~
|| ~~~~~~~~~~~~ ~~~~~~~~~~~~ ||
|| ||
|| ||
|| ||
|| CENTURION ||
|| ||
|| ||
|| -*- ||
|| ||
|| ||
|| InfoMail/386 1.20 ||
|| ||
|| A Document Server for Fidonet Systems ||
|| ||
|| Copyright (C) Damian Walker 1996 ||
|| ||
|| ||
|| -*- ||
|| ||
|| ||
|| USER GUIDE ||
|| ||
|| ||
|| _____ ||
|| (____() ||
|| / / ||
|| / / ||
|| (____() ||
|| _______ ||
|| (_)|||(_) ||
|| ||||| ||
|| ||||| ||
|| ||||| ||
|| ||||| ||
|| ||||| ||
|| ||||| ||
|| ||||| ||
|| /~~~~~\ ||
|| ~~~~~~~ ||
|| ||
|| ||
|| ||
|| ||
|| ____________ ____________ ||
__||__| Copyright |___________________| 1996 |__||__
> |~~~~~~~~~~~~| (C) Damian Walker |~~~~~~~~~~~~| <
~~~~~~ ~~~~~~~~~~~~~~~~~~~ ~~~~~~
InfoMail/386 1.20 User Guide
1. INTRODUCTION
Welcome to InfoMail/386 1.20! This file is the user guide,
which acts as a step-by-step tutorial on setting up a sample
InfoMail installation. You are encouraged to print out this
part of the manual and follow the instructions, especially if
you don't have experience of earlier versions of InfoMail.
To complement this file, there is a user reference document and
a developer's guide. There are also files containing a full
table of contents for all the documentation, and an alphabetic
index referencing pages in all the document files.
1.1. What is InfoMail?
InfoMail/386 1.20 is a document server for Fidonet systems. It
scans your netmail directory for messages addressed to it, and
performs some action based on those messages.
Its basic function is to send out documents which the user has
requested. A document is usually in the form of a text file,
which can be sent in the body of a reply to the user who
requested the document.
A secondary function is to allow users to alter documents
remotely, via netmail. This allows users who cannot run
InfoMail themselves to have their own documents hosted at
another system.
As an extension to its basic function, this version of InfoMail
also allows users to conduct a simple search of the document
list, so that users can find documents on subjects that interest
them. This is especially useful to systems with a large number
of documents.
There are many uses which InfoMail can be put to. It has been
used to send out BBS information, echo descriptions and rules,
reviews of games, FAQ documents and even a price list. The
number of other uses which may be found for it are limited only
by the imagination.
****************************************************************
This program is in the public domain. This means that the
program can be distributed and used, for an unlimited period,
free of charge. If you find InfoMail useful, the author would
be interested to hear from you. Your views on the program, and
the uses you may find for it, are valuable information.
****************************************************************
Introduction U- 2
InfoMail/386 1.20 User Guide
Although the program name and code is protected by copyright,
the author would be pleased to see similar programs appearing
for the PC and other platforms. Should you as an author wish to
write your own document server, feel free to use the data
structures, addressing methods and macros which InfoMail uses.
Feel free also to use 'InfoMail', 'InfoMail Update' and
'InfoMail Search' as the default names for your program to
answer to. The author is more interested in InfoMail as a
widespread idea than as a vehicle for presonal fame and (!)
fortune.
1.2. System Requirements
This version of InfoMail has been written for DOS-based IBM PC
compatibles with an 80386 processor or better. This is a
limitation of the author's compiler, rather than a deliberate
attempt to restrict the systems on which the program will run.
At the time of writing, users of 286s and slower machines may
use InfoMail 1.11, which is still supported. If you wish to see
a new version of InfoMail for 8086-based systems or 286's, let
the author know. If there is enough demand, an 8086 version of
the program will appear.
InfoMail should run on any type of text screen used with
mainstream PC's. It was developed on a VGA system which has had
both colour and monochrome monitors connected during
development. It has yet to be tested with a true monochrome
(Hercules/MDA) system. The program knows nothing of 80x43 or
80x50 text modes, and the full-screen configuration utilities
will only use the top half of an 80x50 screen.
In order to be useful, InfoMail must be used at a Fidonet system
which uses a *.MSG netmail directory. This includes FrontDoor,
Terminate, and also static mailers such as BinkleyTerm and Xenia
if these mailers are used with a mail processor supporting *.MSG
message areas.
The program also requires a DPMI server to be present. It is
supplied with CWSDPMI, a free DPMI server created for the DJGPP
compiler and programs developed with it. If your operating
system does not have its own DPMI server for DOS sessions (e.g.
DOS), CWSDPMI.EXE must be in the current directory or the DOS
path in order for InfoMail to be run.
1.3. Disclaimer
**** IMPORTANT ****
No warranty or guarantee is provided with this program. While
the author has attempted to ensure that the program is fully
operational and bug-free, no responsibility can be taken by the
author in the event that damage or inconvenience is caused by
the program. Run InfoMail at your own risk.
Introduction U- 3
InfoMail/386 1.20 User Guide
1.4. Acknowledgements
Thanks go to the following people for their help in the ongoing
development of InfoMail:
Bill Welch (ex 2:254/222), for beta testing version 1.00.
Bill Birrell (2:2504/200), for beta testing versions 1.00, 1.10,
1.11 and 1.20, and for general programming help in the C echo.
Steven Holme (2:2503/201), for beta testing versions 1.00, 1.10
and 1.20, and for some useful suggestions.
Jim O'Neill (2:256/68), for beta testing version 1.10.
Martyn Wilkins (2:442/608), for promoting version 1.00 in
echomail, and for beta testing versions 1.10, 1.11 and 1.20.
Peter Barley (2:2502/666.15), for beta testing versions 1.00,
1.10, 1.11 and 1.20, and for many useful suggestions.
Andy Altoft (2:2502/666.2107), for beta testing versions 1.00
and 1.10.
Peter Burnett (2:441/80), for some useful suggestions, and for
beta testing versions 1.11 and 1.20.
Joaquim Homrighausen (2:202/330), for hatching versions 1.00 and
1.11 on SDSFRONT, thus attracting interest in the program from
across the world. Also thanks must go to Joaquim for allowing
his interface design to be used for this and previous releases
of InfoMail.
Kev Baillie (2:2502/1), for beta testing versions 1.11 and 1.20,
and for many useful suggestions for 1.20 and future releases of
InfoMail.
Colin Spice (2:440/7), for beta testing version 1.20.
Ronald Troost (2:285/709), for beta testing version 1.20.
1.5. Version History
Version 1.00, original InfoMail, with the following features:
- Alterable name and address
- Universal kill flag for outgoing messages
- 8-character document names
- Posts documents up to 8k in size
Introduction U- 4
InfoMail/386 1.20 User Guide
Version 1.10, first upgrade release, with these additions:
- Global header and footer files for outgoing messages
- 16-character document names
- Document access counter
- Macros for use in headers, footers and documents
- Secret (unlisted) documents
- Expanded subject line for outgoing messages
- Optional kill and other message flags for each document
- Remote maintenance of documents (passworded for security)
- Posts documents up to 16k in size
- Automatic upgrade facility
- Increased speed of document posting
- A couple of aesthetic minor interface bugs fixed
- A 386 version of the program
Version 1.11
- Document List display bug corrected
- Some errors in the documentation were corrected
Version 386 1.20
- Configurable log filename
- Configurable message size up to 64k
- Ability to split large documents into multiple messages
- Option to keep outgoing error messages and notices
- A document list search utility
- Options to keep various types of inbound message
- All outgoing messages are sysop-configurable
- Multiple AKA's per installation
- Indexed (sorted) document list
- Request passwords for added security
- Secondary document messages (useful for held file attaches)
- Optional monochrome 'colour' scheme
- Some extra macros, including two document list macros
Introduction U- 5
InfoMail/386 1.20 User Guide
2. SETTING UP INFOMAIL
The procedure for initially setting up InfoMail will vary,
depending upon whether you are installing the program for the
first time, or upgrading from a previous version. This section
deals with the former case, and assumes that you are starting
from scratch. A later section deals with the procedure for
upgrading.
Before setting up InfoMail for the first time it is necessary to
create a new directory for the program and extract the contents
of the distribution archive into it. Since you are reading
this, it is assumed that you have already got that far.
Then you must ensure that you have a DPMI server set up. If
your operating system doesn't offer a DPMI server for DOS
sessions, or you have disabled it, then you can use CWSDPMI
which is supplied in the archive. Simply copy CWSDPMI.EXE into
a directory on your path; InfoMail will then find it and load it
each time INFOMAIL.EXE is run. See the reference guide section
9.1.2 for further details about CWSDPMI.
The examples in this tutorial use the directory name C:\INFOMAIL
as an example; you will have to adjust all references to this
directory to match whatever directory you are already using for
the program.
To begin with, a simple installation of the program is all that
is necessary; none of the frills need be used. This will be
enough for you to see the program working and get a feel for how
the separate components work, before proceeding to make use of
some of the more complex aspects of the program.
2.1. The Configuration Editor
The first component of the program to visit is the configuration
editor. Assuming that you are in the C:\INFOMAIL directory,
type the following at the command prompt:
INFOMAIL CONFIG
Captialisation is unimportant in this, and all, aspects of
InfoMail. After you have pressed <RETURN>, you should be
presented with the main configuration editor screen, which is
centred upon a window like the following:
Setting Up InfoMail U- 6
InfoMail/386 1.20 User Guide
▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒
▒╒═══════════════════════════════════════════════════════════╕▒▒
▒│ Netmail .\ │░▒
▒│ Log File .\INFOMAIL.LOG │░▒
▒│ Active Yes Max Msg Size 16384 Kill Outb Errors Yes │░▒
▒│ Requests InfoMail Kill Inbound Requests Yes │░▒
▒│ Updates InfoMail Update Kill Inbound Updates Yes │░▒
▒│ Searches InfoMail Search Kill Inbound Searches Yes │░▒
▒│ Header │░▒
▒│ Footer │░▒
▒│ Doc List │░▒
▒│ File Err │░▒
▒│ Inactive │░▒
▒│ Accept │░▒
▒│ Reject │░▒
▒│ Results │░▒
▒│ AKA List │░▒
▒╘═══════════════════════════════════════════════════════════╛░▒
▒▒░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░▒
▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒
As you load the configuration editor for the first time, it
creates the file INFOMAIL.CFG in your InfoMail directory, and
writes to it the default settings shown in the window above.
But since the default settings do not provide a complete and
workable installation, there are a few details you have to
supply yourself.
2.1.1. Netmail Directory
The first field you will have to change is the very top one,
labelled 'Netmail'. The prompt at the bottom of the screen
tells you that this is your *.MSG netmail directory. Unless you
are planning on running InfoMail while in your netmail
directory, you will have to change this field from the default
setting. If your netmail directory is C:\FD\MAIL, you would
enter C:\FD\MAIL in this field.
Notice that the current version of InfoMail supports only *.MSG
type netmail areas. If you currently use a Hudson or JAM area
for your netmail, you will have to change to *.MSGs before you
attempt to use the program.
2.1.2. Log File
The default settings also use the current directory as a
starting point for the log file. Although the current directory
is C:\INFOMAIL at the moment, this probably won't be the case
when you come to run InfoMail as a regular part of your setup.
So the 'Log File' field will have to be changed to explicitly
show the full pathname of your log file.
Setting Up InfoMail U- 7
InfoMail/386 1.20 User Guide
Assuming you want your log file to reside in the InfoMail
directory, this field should contain 'C:\INFOMAIL\INFOMAIL.LOG'.
Note that the file doesn't have to be called INFOMAIL.LOG; some
sysops like to append the logs of all their software onto the
same file.
2.1.3. AKA List
The only other field that needs changing in the configuration
editor is the AKA List. When you first install InfoMail there
are no addresses stored, since the program has no idea what your
Fidonet addresses are.
To add your address, select the 'AKA List' label. This will
take you to a submenu, which contains options for adding and
deleting addresses to the list. No edit option is provided; to
change an address you must delete the old address and add a new
one.
To add an address, press INS as the prompt at the foot of the
screen indicates. Then a cursor appears and you can enter a 4D
Fidonet address; for Centurion this would be 2:2502/666. Enter
your address here, and press ENTER. The AKA List menu will
reappear.
If you have further addresses you want to add to InfoMail, do it
now. InfoMail can cope with as many AKAs as will fit in memory,
but it will only display as many as can fit on the screen beside
the 'AKA List' label. So if you have a lot of AKA's, make sure
you're entering them correctly.
If you make a mistake while adding your AKAs, or you want to
delete an AKA for another reason, press DEL on the AKA List menu
and type in the address you want to delete. It will then
disappear from the AKA list.
Once you have finished adding addresses, press ESC to exit the
AKA List menu.
2.1.4. Other Fields to Edit
Now you have done all you need to do in the Configuration
Editor. However, there are a few fields which will not be
revisited later in this tutorial, so they will be explained
here.
The 'Requests', 'Updates' and 'Searches' fields define the names
that InfoMail will answer to. It is recommended that you leave
these as they are, in order to maintain some sort of standard
from the users' point of view; most current installations of
InfoMail 1.11 around the world answer to the names of 'InfoMail'
and 'InfoMail Update'.
Setting Up InfoMail U- 8
InfoMail/386 1.20 User Guide
However, if you really want to change these names then it is
simply a case of changing the relevant fields on the
configuration screen. If you want to do something silly such as
using the same name for all three, then the Request name would
take precedence over the other two names, with the Update name
coming next; i.e. if you change these fields to:
▒│ Requests SillyServer Kill Inbound Yes │░▒
▒│ Updates SillyServer Kill Inbound Yes │░▒
▒│ Searches SillyServer Kill Inbound Yes │░▒
then InfoMail will accept a message to 'SillyServer' as a
document request. If the 'Requests' field were then changed to
something else, then a message to 'SillyServer' would be taken
as a document update.
2.1.5. Exiting the Configuration Editor
To exit from the configuration editor just press ESC. Any
changes to the configuration will be saved to the file
INFOMAIL.CFG when before the command prompt reappears.
2.2. Setting Up Documents
Your next task in getting InfoMail up and running is to define
one or more documents, since a document server without any
documents could hardly be regarded as useful. The tool for this
job is the Document List Editor, which is invoked by typing:
INFOMAIL LIST
at the command prompt. Upon issuing this command, you will be
presented with a screen of which the central window resembles
the following:
▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒
▒╒═══════════════════════════════════════════════════════════╕▒▒
▒│ X Document Subject │▒▒
▒│ │░▒
▒│ │░▒
▒│ │░▒
▒│ │░▒
▒│ │░▒
▒│ │░▒
▒│ │░▒
▒│ │░▒
▒│ │░▒
▒│ │░▒
▒╘═══════════════════════════════════════════════════════════╛░▒
▒▒░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░▒
▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒
Setting Up InfoMail U- 9
InfoMail/386 1.20 User Guide
The first time you load the Document List Editor, two files will
be created: INFOMAIL.DAT and INFOMAIL.NDX. These are the
document list files. The document list is always sorted
alphabetically, hence the presence of an index file
INFOMAIL.NDX. Currently the document list is empty.
2.2.1. Adding a Document
The procedure for adding a document is very easy-- just press
INS. A blank document record will appear, looking something
like this:
▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒
▒╒═══════════════════════════════════════════════════════════╕▒▒
▒│ Document ░░░░░░░░░░░░░░░░ │░▒
▒│ Active? │░▒
▒│ Listed? │░▒
▒│ Macros? │░▒
▒│ Routing │░▒
▒│ Subject │░▒
▒│ Status │░▒
▒│ Request │░▒
▒│ Update │░▒
▒│ File │░▒
▒│ 2nd File │░▒
▒│ Accesses │░▒
▒╘═══════════════════════════════════════════════════════════╛░▒
▒▒░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░▒
▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒
InfoMail is waiting for you to enter a name for the new
document. At this point your options are twofold. You can
press ESC or ENTER (leaving the document name blank), in which
case you will be returned to the document list window without
having added a document.
A far more sensible option is to enter a document name here and
now. There is a sample document supplied with the InfoMail
archive, which will be used to illustrate the procedure. For
want of a better name, call this document 'Sample' (without the
quotes). Once you have entered the document name, some default
field values appear, and you can alter the values of some of the
fields.
2.2.2. Subject Line
The first field to change for this example is the 'Subject'
field. This is the subject line which will grace outbound
messages containing this document, each time it is requested.
At the very least, it should contain the name of the document,
but since it is independent of the document name it can contain
something a little more descriptive. For this example, enter 'A
sample document' as the subject.
Setting Up InfoMail U-10
InfoMail/386 1.20 User Guide
2.2.3. Document Filename
You will need to tell InfoMail where it can find the document
file itself, for when it comes to post it in response to a
user's request. This is what the 'File' field is for, and it
should contain the full path and filename of the document text
file. The sample file supplied is called DOCUMENT.SAM, so you
should enter C:\INFOMAIL\DOCUMENT.SAM as the document filename.
2.2.4. Saving the Document Record
The subject and filename are the only two fields which need to
be altered in order to set up a document; for the time being,
all the other fields can be left as they are. To save the
document record simply press ESC. InfoMail will save an
incomplete record (for later completion, perhaps) if you press
ESC before having entered all the necessary fields.
For a bit of practice, set up another document. Call this one
what you like, and give it any subject line that takes your
fancy. When you come to enter the filename, make sure the file
doesn't yet exist; i.e. don't try to use an existing text file
on your system for this example. This document entry will be
used to illustrate how to build up a document text file. The
examples in this document will assume the name 'MyDocument' has
been used, with the description 'My Example Document' and the
filename 'C:\INFOMAIL\MY.DOC'.
2.2.5. Editing and Deleting Documents
To edit a document after you've saved it, you just highlight its
entry in the document list window and press ENTER. The document
record will reappear, and you can alter the fields in the same
manner as when you first entered the record. Note that the
document name cannot be edited on an existing document record.
Deleting and undeleting documents is easy. If you want to try
out an example, add another document record to play with. Since
you're just going to delete the document, you don't really need
to enter a subject line or filename for it.
To delete a document record, highlight its entry in the document
list and press DEL. An asterisk (*) will appear next to the
document name, signifying that the record is to be deleted.
Pressing DEL again will remove the asterisk, thus providing an
undelete function.
2.2.6. Exiting the Document List Editor
To exit the Document List Editor just press ESC while browsing
the document list window. All records have already been saved
before you reach this point, since they are saved and sorted as
you finish entering the details of each record.
Setting Up InfoMail U-11
InfoMail/386 1.20 User Guide
It is at this point that any records you have marked as deleted
are removed permanently, so be careful when deleting a lot of
records. There is no separate 'purge' or 'pack' option for the
document list, it's all done each time you exit the Document
List Editor.
2.3. Creating Document Text Files
InfoMail documents are standard ASCII text files. You can use
any text file of up to 64k in size as an InfoMail document, and
often InfoMail is used as a means of distribution of existing
documents such as BBS bulletins or files available for FReq,
rather than having documents created specifically for it.
If you have been following the examples so far, you should have
two documents set up. One, 'Sample', already has a text file;
if you want to see it, then view the file DOCUMENT.SAM using a
text editor or the DOS TYPE command. The other document, named
'MyDocument' for the sake of the following examples, does not
yet have a text file, and it is this example which this section
will deal with.
The first thing to do is to create the text file for this
example. Edit the file MY.DOC (or whatever filename you have
chosen), and put in some text. You could import some text from
an existing file if you like.
There is nothing special about InfoMail document text files.
They use standard ASCII carriage return/linefeed pairs, and may
use any characters which your network allows in netmail
messages. There are some tips for more effective-looking
documents, though.
The first of these involves the way that Fidonet message editors
read, display and (sometimes) write messages. Fidonet messages
are reformatted in real time by message readers. This allows
the margins of a single message to differ on each recipient's
screen, depending on the individual recipient's display size and
software setup.
Because of this, most good message editors only include a
carriage return only at the end of a paragraph, rather than at
the end of each line. The message reader will automatically
word wrap the paragraphs when the message is received.
Since text files used by InfoMail are destined to end up as
Fidonet messages, they may make use of this facility. If you
are creating a text file which is used exclusively as a document
for a document server, it may be a good idea to format the file
with each paragraph on a single line.
Setting Up InfoMail U-12
InfoMail/386 1.20 User Guide
Such a text file would look ugly in most DOS text editors, and
it may be necessary to reformat the file with a CR/LF at the end
of each line while editing, removing the extra CR/LFs before you
save the text. If you don't edit the file that often then you
may find it worth the effort to produce a better looking result
at the users' end.
Kludge lines may be included in document text files if you feel
the need. For example, you may like to preserve the character
set used for users whose message readers support this feature.
Kludges should be included as they are in normal messages, i.e.
with the ASCII character 1 (smiley face) as the first character
on the line.
You may find it entertaining to try and confuse InfoMail by
including addressing information kludges in your document text
file. However, all addressing kludges and the PID will be
replaced by corrected kludges in the outgoing message when the
document comes to be posted.
2.4. Testing out Your Installation
Assuming you've followed the steps so far, you should have a
ready-to-use configuration with your address(es), netmail
directory and log filename set up, you should have two documents
in the document list, and both documents should have a text file
ready to post. So all that's needed now is to try out the
program and see how (if?) it works.
In order to test the setup properly, you'll need to have a
message waiting for InfoMail to pick up. So load your message
editor and enter the following netmail:
================================================================
By: <your name>, <your address>
To: InfoMail, <your address>
Re: Sample
----------------------------------------------------------------
<whatever you like here>
================================================================
This is the format of an InfoMail request message. If you've
changed the 'Request' name in the configuration editor, then the
new name you supplied should go in the 'To:' field, in place of
'InfoMail'. The address in the 'To:' field should be one of the
addresses in the AKA list, and the message body of a document
request is ignored, so you can put anything you like in there.
Note: It's a bad idea to leave the message body completely blank
when you're requesting a document from another system, since
some mailers and mail processors delete netmails which lack
text, before other programs get to see them.
Setting Up InfoMail U-13
InfoMail/386 1.20 User Guide
Once you've saved the message, you can exit from the message
editor and run InfoMail's netmail scan. Assuming you are back
in the C:\INFOMAIL directory, type the following at the command
prompt:
INFOMAIL SCAN
This is the heart of InfoMail, where the program actually does
the job it was designed for. If you've entered the request
message correctly, you should see the following message appear
on the screen:
* Processing request from <your name>, <your address>
When InfoMail has scanned all the netmails in your netmail
directory, the message '* Finished!' should appear and the
command prompt should return. If you reload your message
editor, you should see that InfoMail has posted the following
message in response to your request:
================================================================
By: InfoMail/386 1.20, <your address>
To: <your name>, <your address>
Re: A Sample Document
----------------------------------------------------------------
Welcome to InfoMail/386 1.20!
This is a sample document created for the tutorial in the User
Guide. Please see the user guide for more details.
================================================================
Try repeating the procedure for the second document you set up
in the Document List Editor. Assuming everything works
correctly, you are now ready to add InfoMail to your batch files
as a fully functioning part of your system.
2.5. Running InfoMail Regularly
The exact procedures here will differ from system to system. If
you are a point, you will either want to run InfoMail manually,
or if you are using a system based on batch files then you will
want to add InfoMail to your polling batch file.
If you are a node then you should run InfoMail automatically--
either once per day in your daily maintenance, or after each
call when mail is received. The latter method is used at the
author's system, meaning that incoming document requests are
dealt with immediately.
Either way, it would be useful to be able run InfoMail from
outside its own directory. InfoMail provides for this
possibility in two ways. The first way is using a -PATH switch
on the command line. The way to use the path switch is as
follows:
Setting Up InfoMail U-14
InfoMail/386 1.20 User Guide
INFOMAIL SCAN -PATH C:\INFOMAIL
This assumes that the C:\INFOMAIL directory is in your path; if
not then the full pathname to INFOMAIL.EXE would be required, as
in:
C:\INFOMAIL\INFOMAIL SCAN -PATH C:\INFOMAIL
The -PATH switch can also be used in conjunction with the LIST
and CONFIG commands, allowing the configuration editor and the
document list editor to be loaded from outside InfoMail's own
directory.
However, the -PATH parameter makes cumbersome command lines, so
an alternative method is provided for running InfoMail from
outside its own directory, and this is more in line with other
comms-related programs. This method is the INFOMAIL environment
variable. In your AUTOEXEC.BAT, or at some other time before
you run infomail, you would set the INFOMAIL environment
variable as follows:
SET INFOMAIL=C:\INFOMAIL
If the -PATH switch is omitted from the INFOMAIL command line,
then the program looks for the INFOMAIL environment variable in
order to locate the config and document list files.
Note that the -PATH switch overrides the environment variable.
Note also that filenames of documents and the log file are not
affected by either -PATH or the INFOMAIL environment variable;
you still need to enter a full path for those.
One more command line parameter which is useful for all parts of
InfoMail (i.e. the SCAN, LIST, CONFIG and UPGRADE commands) is
the -MONO switch. Adding this to any valid InfoMail command
line will cause the program to use a 'colour' set which is more
appropriate to display on monochrome screens.
Once you have put InfoMail in your mail system's batch file, it
will be fully operational, and the initial setup is complete. It
will respond to document requests from other systems in the same
way as it responded to your own requests. Perhaps now is a good
time to replace 'Sample' and 'MyDocument' with some genuinely
useful documents.
2.6. Upgrading InfoMail
This section is exclusively for those who are upgrading from a
previous version of InfoMail. If you've installed InfoMail from
scratch, you will want to skip this section.
If you are upgrading from a previous version of InfoMail, there
is a utility included with the package to allow you to set up
InfoMail/386 1.20 quickly and easily, using your existing
configuration files from InfoMail 1.00, 1.10 or 1.11.
Setting Up InfoMail U-15
InfoMail/386 1.20 User Guide
Before upgrading your setup, it is advisable that you make a
full backup of your existing InfoMail directory. A simple copy
operation to a temporary directory will do the trick, or perhaps
you would like to archive your existing installation for a
longer term so that you can ensure your InfoMail/386 1.20 setup
works correctly over a period of time.
After you have backed up your directory, remove all the standard
InfoMail files apart from INFOMAIL.CFG and INFOMAIL.DAT. Unless
you have extra files in the directory (such as headers, footers
or documents) the easiest way to do this is to delete everything
and copy the two files named above back into your InfoMail
directory.
Now is the time to unpack the InfoMail/386 1.20 archive into
your InfoMail directory. Once this is done, you're ready to run
the InfoMail upgrade utility. Type the following at the command
line:
INFOMAIL UPGRADE
If all goes well, you should see three messages on the screen.
The first tells you that the configuration file is being
upgraded. The second tells you that the document list file is
being upgraded; if you have a lot of documents then this could
take some time. The final message tells you that the process is
finished.
This upgrade procedure upgrades your existing setup almost
exactly, but you may need to alter the log file settings.
If, before running INFOMAIL UPGRADE, you have used the -PATH
parameter to direct InfoMail to its data files, as described in
a previous section, or you have an INFOMAIL environment variable
set up, then your log file should take its pathname from this,
and InfoMail will add to the existing log file.
If you didn't use -PATH or the INFOMAIL environment variable
then the log file will always be written to whatever the current
directory is when InfoMail is run. In this case, you have to
put a full path name in the 'Log File' field. To load the
configuration editor, type:
INFOMAIL CONFIG
and select the 'Log File' field label. You will now be given an
opportunity to enter a more acceptable log filename, such as
C:\INFOMAIL\INFOMAIL.LOG. Once you have set the log filename,
press ESC to exit from the configuration editor.
The next change you have to make is to the InfoMail command
line in your batch files, as the syntax has been changed for
this version. You should implement the following changes in
batch files and any other place you call InfoMail:
Setting Up InfoMail U-16
InfoMail/386 1.20 User Guide
What was... Becomes...
-Pdirectory -PATH directory
-S CONFIG
-L LIST
-U UPGRADE
-? <nothing>
<nothing> SCAN
Notice that INFOMAIL by itself now displays help, and to run a
netmail scan you need to issue the command INFOMAIL SCAN. See
also the added -MONO switch discussed in section 2.1.5.
Apart from these small details, the upgrade procedure creates an
installation of InfoMail/386 1.20 which directly imitates the
earlier version of the program, and doesn't take advantage of
any of the more advanced features of InfoMail/386 1.20.
The following sections of this manual, which deal with those
more advanced features, will be useful for first-time users and
upgrading users alike.
Setting Up InfoMail U-17
InfoMail/386 1.20 User Guide
3. MORE CONTROL OVER YOUR DOCUMENTS
This section deals with some of the more advanced features of
InfoMail, concerning the behaviour of individual documents, and
the display of their contents to remote users.
3.1. Creating Secret Documents
Sometimes it is desirable or necessary to create documents which
are for restricted viewing, or which should only be approached
from certain channels such as references in another document on
your system. This subsection deals with creating such
documents.
3.1.1. Hidden Documents
When a user attempts to request a document which is not present
on your system, a message is sent in reply telling them that the
document they wanted does not exist. Included in this message
as standard is a brief list of documents, hence this particular
response is known as the 'Document List'.
It is possible to prevent a document appearing in document list.
The reasons for doing this are obvious: it ensures that a
particular 'secret' document doesn't come to the attention of a
casual browser who has stumbled upon the document list.
The author uses this facility to esure that certain documents
are approached through the 'proper' channels, creating a proper
hierarchy of information with designated entry points. If a
user knows the name of a document which is unlisted, they may
still request it without requesting the associated listed
document, of course.
Other sysops use this feature to create secret documents. The
document is unlisted, and its name is known only to those they
tell about the document, thus the document name acts as its own
password.
To flag a document as being hidden from the document list, a
field exists in the document list record, labelled 'Listed'.
Setting this field to 'No' on a document prevents that
particular document from appearing in a document list.
3.1.2. Password Protection
Sometimes the above is not enough to prevent sensitive documents
from being seen by prying eyes. Or perhaps for some reason you
want to have a listed document which is not available to all and
sundry. In which case, a feature new to InfoMail/386 1.20 is
available, which allows you to password protect any document,
listed or not.
More Control over your Documents U-18
InfoMail/386 1.20 User Guide
As with hidden documents, password protection is available via
the document list editor, by setting a field in the document
list record. This is labelled 'Request' (not 'Password', since
there is another password associated with documents, covered
later).
Setting the request password means that a password must be
supplied on the subject line of a request message, as in the
following example:
================================================================
By: <your name>, <your address>
To: InfoMail, <your address>
Re: Sample <password>
----------------------------------------------------------------
<whatever you like here>
================================================================
If the password is omitted from a request, InfoMail posts an
error message informing the user that their request was
rejected.
Leaving the request password blank means that a password is not
required for the document. So the same error message will be
sent to a user who adds a password to a request for a document
which doesn't have one.
3.2. Using Expandable Macros
A feature available in versions of InfoMail from 1.10 onwards is
the availability of expandable macros which may be placed in the
document text. This allows information to be added to documents
which might differ each time the document is requested.
Macros are surrounded by braces (i.e. '{' and '}'), and consist
of a letter and an optional number; the number may come before
or after the letter within the macro; InfoMail isn't fussy about
this.
Including the number in a macro ensures that the macro is always
expanded to a constant length, allowing macros to be used in
tables without affecting the formatting. Each particular macro
type has a maximum size, and exceeding this size in the length
number you include in the individual macro will result in a
macro of the maximum size being produced; thus {D23} would
produce a 16-character document name.
Omitting the length number is more usual for including a macro
in normal text. Since the length of the resulting expanded
macro is variable, notice should be taken of the hint in section
2.1.3, to include entire paragraphs on one line. This means
that the outgoing document message will be reformatted in an
aesthetically pleasing way by the user's message reader.
More Control over your Documents U-19
InfoMail/386 1.20 User Guide
Note that expanded macro output is never truncated by including
a length number. Thus the document 'MyDocument', when used with
a macro {D8} would be output as 'MyDocument' not 'MyDocume'.
Macros useful in documents include the program ID, the request
name and address for InfoMail, the name and Fidonet address of
the user, details about the current document, a document access
counter, and even a document list.
It is a bad idea to include macros in documents which are also
available by file request, or as bulletins for BBS users. This
is because the macros will only be expanded when the message is
requested via InfoMail (your BBS software and your file request
processor know nothing of InfoMail macros).
3.2.1. Program Information
It is simple to include the program name and version in your
documents (in this release, 'InfoMail/386 1.20'). The macro for
doing this is {P} or {P<number>}, where <number> is in the range
1 to 35.
The advantage of including this macro instead of the text
'InfoMail/386 1.20' in your document is that the macro will
change if you upgrade your installation of InfoMail. Thus a
document which has the following in its text file:
Document produced by {P}
Would produce the output 'Document sent by InfoMail 1.11' if you
were using version 1.11 of InfoMail, but would have changed
automatically to 'Document sent by InfoMail/386 1.20' when you
upgrade the software.
Also available as macros are the request name and the AKA in use
by InfoMail for the current message. These use the macros
{I<number>} and {A<number>}, where {I} is the InfoMail request
name and {A} is the AKA. The maximum macro length for the
InfoMail request name is 35, and the maximum length of the AKA
is 23. So, in a document containing the following in its text
file:
If you send the following message:
========================================================
To: {I}, {A}
Re: ABOUT
--------------------------------------------------------
(anything in the message body)
========================================================
then information about this system will be returned to
you via routed netmail.
More Control over your Documents U-20
InfoMail/386 1.20 User Guide
the 'To:' line would be expanded into something resembling the
following:
To: InfoMail, 2:2502/666
The address would be the AKA to which the user had sent the
request message, so the correct AKA should always be returned
for the user's network.
3.2.2. User Details
The user's name can be included in the document using the {N} or
{N<number>} macro, where <number> ranges from 1 to 35. The
user's full name is used from the incoming request message.
Similarly, the user's Fidonet address can be included using the
{U} or {U<number>} macro, where {number} ranges from 1 to 23.
This allows us to elaborate upon the latest example given in
section 3.2.1, as follows:
If you send the following message:
========================================================
By: {N}, {U}
To: {I}, {A}
Re: ABOUT
--------------------------------------------------------
(anything in the message body)
========================================================
then information about this system will be returned to
you via routed netmail.
If the user 'Damian Walker' of 2:2502/666.3 writes to InfoMail
at 2:2502/666, requesting the document above, the document
posted in response would contain this:
========================================================
By: Damian Walker, 2:2502/666.3
To: InfoMail, 2:2502/666
Re: ABOUT
--------------------------------------------------------
As well as the full user name, the first and last names of the
user can also be included in the document using the {F} and {L}
macros respectively. Each of these macros can contain a
constant length of 1 to 35 characters. As an example, a
document could contain the following as its first line:
More Control over your Documents U-21
InfoMail/386 1.20 User Guide
Hello {F}!
in which case the outgoing document would start with:
Hello Damian!
if the author had requested a document. Possible uses of the
{L} macro are not as readily apparent, but it was included in
the package for the sake of completeness.
3.2.3. Document Record Information
Various fields from the document record can be included as
document macros. The most useful example of this is the
document name, which is included using the macro {D} or
{D<number>}, where <number> ranges from 1 to 16. The subject
line can also be included, using the {S} or {S<number>} macro:
<number> in this case ranges from 1 to 71. In order to
illustrate these, look at the following example:
Thank you for requesting document "{D}", entitled "{S}"
which would be expanded to something resembling the following in
an outgoing document message:
Thank you for requesting document "Sample", entitled "A
Sample Document"
In response to a request from an InfoMail user, the operating
system filename of the document has been included as a macro as
from InfoMail/386 1.20. This is the {O} or {O<number>} macro,
where <number> ranges from 1 to 63. So the document containing
this in its text file:
This is the file {O}
might be expanded to
This is the file C:\INFOMAIL\DOCUMENT.SAM
in an outgoing document message.
The final document-related macro is the access counter. This
corresponds to the 'Accesses' field in the document list record,
and it is increased by one each time the document is requested.
So as well as letting the sysop know how often a document has
been requested, this information can also be relayed to users,
using the {C} or {C<number>} macro, where <number> ranges from 1
to 5. Something like:
More Control over your Documents U-22
InfoMail/386 1.20 User Guide
This document has been accessed {C} time(s)
might expand to
This document has been accessed 15 time(s)
in an outgoing document message. Although the 'Accesses' field
cannot be directly edited in the document list editor, it can be
reset to 0 simply by select the field. This is useful when you
are requesting a document a number of times to test its initial
setup; resetting the access counter to 0 afterwards gives a more
accurate count to the user.
3.2.4. Document List
Document lists can be included in documents themselves. This
allows you to set up a dedicated 'List' document for example,
one which you can advertise to users, but which doesn't include
the 'error' overtones of the standard document list response.
A standard-style document list as used by InfoMail itself can be
included in any document using the {W} macro ({D} already being
used for the document name). Think of {W} meaning 'what' as in
'what documents are available'. Output of the following
document:
The following documents are available by sending a
message to {I} and {A} with the document name on the
subject line:
<blank line>
{W}
<blank line>
(end of list)
would look something like:
The following documents are available by sending a
message to InfoMail at 2:2502/666 with the document name
on the subject line:
Sample MyDocument
(end of list)
Another macro exists which gives a document name and subject
line for each document. This is the {X} macro (eXpanded list,
if you like); replacing the {W} in the previous example with an
{X} would create the following output to users requesting the
document:
The following documents are available by sending a
message to InfoMail at 2:2502/666 with the document name
on the subject line:
More Control over your Documents U-23
InfoMail/386 1.20 User Guide
Sample A Sample Document
MyDocument My Example Document
(end of list)
This is much more informative as a document list, although the
output can be a bit bulky if you have a lot of (listed)
documents on line, hence the default document list described in
section 3.1.1 uses the {W} macro output.
Note that if you include a length number in the {W} or {X}
macro, it will be ignored. The output of these macros is not
suitable for inclusion as a single field in a table, so a length
number is of no use.
3.2.5. Other Macro Considerations
The option to switch macros off is provided, particularly since
you may want to use InfoMail to post documents automatically
generated by some other piece of software. If such documents
contain brace characters ('{') InfoMail will become confused as
it tries to expand them as macros-- unless you set 'Macros' to
'No' to prevent macro expansion in that particular document.
If you wish to include a left brace in a document over which you
have control of the contents, you can do this using the {{}
macro (i.e. a left brace within a pair of braces). Right braces
can be used indiscriminately, except within macros. But since
no valid macro contains a right brace character, there is no
reason to try and do this anyway.
3.3. File Attaches and Direct Messages
In response to requests from InfoMail users, a feature was added
to InfoMail 1.10 onwards, to allow file attaches to be created
in response to document requests. Since file attaches can
rarely be routed, you also have the option of crashmailing any
document response (which could be expensive), or putting it on
hold for the requesting user to pick up.
3.3.1. Setting the Status Field for File Attaches
To create a file attach, you must make some changes to the
document record in the document list editor. The first field
which must be changed is the 'Status' field. When you edit the
Status field, you are presented with six options at the foot of
the screen, which are the various message attributes supported
by InfoMail. The main one you are interested for file attaches
is 'File', toggled by pressing 'F'.
Unless some form of file routing is set in place in your
network, you will have to crash the document file attach or put
it on hold. The 'Crash' and 'Hold' attributes provide for this,
and may be toggled using the 'C' and 'H' keys respectively.
More Control over your Documents U-24
InfoMail/386 1.20 User Guide
In addition to this, you will of course have to include the name
of the attached file as the 'Subject' field, as is normal
Fidonet practice for file attaches.
Bear in mind that if you use the {X} macro to create document
lists, the filename of the attached file will appear as the
subject of the document in the list. If this looks too ugly for
your taste, you could mark the document as unlisted.
Although the message is a file attach message, you will still
have to create a document text file in addition to whatever file
you are attaching. Treat this as a covering note for the file
attach, a message informing the user of the name of file they
have just received.
3.3.2. Considerations for File Attaches on Hold
If you have created a file attach which will be held for users
to pick up, they will want to know when that file is available.
This is where the seconary document file comes in. The '2nd
File' field of the document record defines a secondary file
which will be posted when the document is requested; this
differs from the primary document file in that it is always sent
via routed netmail, and it will never contain any attribute
other than Pvt, Local, Kill (if Kill is one of the attributes in
the Status field).
You would use the secondary document to inform users that the
file was waiting at your system for pickup. This prevents them
from having to estimate how long their request has taken to
reach your system and how often you process InfoMail requests.
Another thing to consider about file attaches on hold is that
the requesting user may never pick them up. InfoMail does not
currently check outgoing messages, so you will have to scan your
netmail directory manually for file attaches which have not been
picked up, or use a netmail tool like NetMgr.
3.3.3. Using the Status Field for Other Purposes
As well as file attaches, the Status field can be used for file
requests or file updates, simply by including the correct
attribute in the document record, in conjunction with the Crash
or Hold attributes as appropriate. The uses for including File
requests or Update requests as outgoing documents are not
exactly obvious, but some enterprising user may come up with
some way to use the feature.
The other attribute supported by InfoMail is 'Kill'. Setting
'Kill' on a document means that outgoing document messages will
have the 'Kill' flag set; this prevents your netmail directory
(or 'Sent Netmail' area) from being clogged up by responses from
InfoMail.
More Control over your Documents U-25
InfoMail/386 1.20 User Guide
3.4. Remotely Updating Documents
The remote update is a very useful feature added to InfoMail in
version 1.10, allowing remote users to maintain documents on
your system. This is useful in the event that a remote user
cannot run InfoMail; perhaps they are a BBS user, they run their
mailer on a platform other than the DOS PC, or they use a
message area type other than *.MSG for their netmail.
All the local sysop has to do is set the document up in the
first place. The document would be set up in the document list
editor like any other document, but in addition, a password
would be set protecting the document against update by
unauthorised users. The update password is set using the
'Update' field in the document list editor, and it acts in a
similar fashion to the 'Request' password. However, lack of an
update password does not allow the document to be updated
without a password; it prevents the document from being updated
at all. This is how you prevent your normal documents from
being updated remotely.
To update their document, all the user has to do is send a
message like the following:
================================================================
By: <user name>, <user address>
To: InfoMail Update, 2:2502/666
Re: <document> <password>
----------------------------------------------------------------
New document contents go in the message body
================================================================
'InfoMail Update' is the update name as set up in the
configuration editor; if this has been changed, then obviously
the new update name should be used instead of 'InfoMail Update'.
The address would obviously vary to suit your system.
When such an update message is received by InfoMail, the
contents of the message body are placed in the document file as
named by the 'File' field in the document record. InfoMail
posts a response message when it updates a document, as
confirmation to the updating user. The secondary document file
remains unchanged, as does the actual document record; only the
contents of the primary document file may be updated in this
way.
Notice that kludges from the incoming message are included in
the document file, including MSGID, TOPT, FMPT, INTL and PID.
This is no reason to worry, though. These are replaced with the
correct information by InfoMail when it posts the file to users.
The kludges were left in the document file in order that special
information such as character sets could be left as the document
updater intended; InfoMail 1.10/1.11 would remove all kludges,
so such information was lost.
More Control over your Documents U-26
InfoMail/386 1.20 User Guide
3.5. Making a Document Temporarily Inactive
There are times when you don't want a document on your system to
be requested. Sometimes this is when the information becomes
out of date, or you are waiting for a document update to arrive
from a remote user before allowing the document to be requested.
In the former case, the document could simply be deleted, and
reinstated when updated information becomes available. However,
this means that the document record has to be recreated, which
could become tiresome if a large number of documents should be
inactivated for a period of time.
In the latter case the document couldn't be deleted, as an
update would then be rejected. It could be marked as unlisted,
but this wouldn't prevent users from requesting the document
and, if the first document update hadn't arrived, users would
receive a disconcerting error message saying the file is
missing.
To cover for these eventualities, a document flag 'Active' is
available. When set to 'No', document requests are politely
rejected, and the user is informed that the document is
temporarily off-line. When you want to activate the document
again, you simply set the 'Active' field to 'Yes'.
More Control over your Documents U-27
InfoMail/386 1.20 User Guide
4. MORE CONTROL OF YOUR OVERALL SETUP
There are some facilities offered in InfoMail's configuration
editor which allow manipulation of the overall behaviour of the
program (as opposed to behaviour of individual documents). This
section tells you how to make good use of these.
4.1. Different Log Files
Upon loading the configuration editor, you can see that one of
the fields is 'Log File'. This allows you to set the log file
for InfoMail to write to. Note: this field is not optional. If
InfoMail cannot create or open its log file, it will not run.
The log file is important in tracking down mistakes in
configuration.
Some sysops like to combine the log files for all their software
into one file. Other sysops keep separate log files for each
piece of software, but all in one directory. Whatever your
preference, you can use the 'Log File' field to set up the log
file as whatever file/pathname you want.
The InfoMail log file is in a format shared by a number of other
Fidonet programs, so combining the log file with that of, say,
FrontDoor or RemoteAccess (compact setting) will still produce a
log file which is cleanly laid-out and easy to read.
4.2. What to Do with Inbound and Outbound Messages
InfoMail offers you the option of whether to kill inbound
messages or to mark them as 'Rcvd' after processing. Separate
controls are given for inbound document requests, updates and
searches.
There are three fields in the configuration editor labelled
'Kill Inbound ...', one for requests, one for updates and one
for searches. When one of these is set to 'Yes', inbound
messages of the appropriate type are deleted when they have been
processed. If you set one of these to 'No', messages of that
type will be kept, and marked as 'Rcvd' (so that InfoMail will
not attempt to process them again). Setting one or more of
these fields to 'No' can act as a diagnostic aid, for instance,
when users contact you regarding failed requests, updates and
searches.
Another field is available, entitled 'Kill Outbound Errors'.
This allows you to specify whether outgoing messages which are
not document messages (such as document lists, update
confirmation, search results and error messages) have the 'Kill'
flag set. Again, this is useful as a diagnostic tool, and it
allows you to view what the outbound messages look like during
the normal use of the program.
More Control of your Overall Setup U-28
InfoMail/386 1.20 User Guide
4.3. Message Headers and Footers
InfoMail allows you to add a standard header and footer to all
your outbound messages, including documents, document lists and
all other messages. You can specify a header and footer file by
simply entering the full path and filename of the header and/or
footer files in the 'Header' and 'Footer' fields of the
configuration editor.
If the 'Header' field is left blank, no header file precedes the
normal text of outgoing messages. Similarly, the 'Footer' field
can be left blank to prevent a footer from being added to each
outgoing message.
Headers and footers may contain macros just like documents, so
you could include a standard greeting like
Hi {F}!
<blank line>
as your header. These macros are always expanded, regardless of
the 'Macros' setting of the document being posted. The
behaviour of some of these macros varies when the outgoing
message the header/footer is attached to is not a document (e.g.
the {D} macro is not a document name on the document list
message, but the name of the non-existent document requested by
the user).
4.4. Splitting Large Messages
The maximum size of outgoing InfoMail messages is 64k. However,
this is still too large for some systems, so it may be a good
idea to limit the outbound message size even further. This is
where the 'Max Message Size' field becomes useful.
As default, this is set to 16k (16384), which is often the upper
limit of some mail processing software. It could be argued that
this is about the largest message you would want to send via
routed netmail, but this limit should not apply to documents
sent directly or held for direct pickup. The option is given
to increase this to a value not exceeding 65535, or even to
decrease it if your uplink is having trouble with messages of
this size.
Instead of truncating larger messages, the messages will be
split into chunks of whatever you have set the 'Max Message
Size' to. So a document of around 64k would be split into four
messages of 16k if the default maximum size is used (not
counting kludges, headers and footers). Documents over 64k will
always be truncated, however.
More Control of your Overall Setup U-29
InfoMail/386 1.20 User Guide
When creating large documents, bear in mind the fact that other
systems may decide not to route them. It might be a good idea
to consult your uplink(s) before implementing large documents in
InfoMail, or alternatively, send large documents directly or put
them on hold. In this latter instance, a small text file set up
as a secondary document could inform users that the main
document is ready for direct pickup.
4.5. Customising the Standard Responses
After a number of requests from users of InfoMail to allow the
document list message to be customised, the facility was added
to allow customisation of all outgoing InfoMail errors and
non-document responses. This is the purpose of the fields 'Doc
List', 'File Err', 'Inactive', 'Accept', 'Reject' and 'Results'
in the configuration editor.
To customise one of these messages, simply create a text file
with the message you want to send to the user, and include the
filename in the relevant field in the configuration editor. In
effect, you are creating 'special' documents which are sent in
response to events, rather than normal document requests.
Macros are expanded in all response messages, and because of
this, some of the standard InfoMail responses deserve more
detailed consideration.
4.5.1. Customising the Document List
Although the name of this response is 'document list', it is not
necessary to post a full document list to users when they
request a non-existent document. This is particularly useful if
there are a lot of mistakes made by users requesting documents,
or you have a lot of documents on-line.
When creating the document list message, the choice is yours if
and how you include the document list. If you want a standard
document list, include the {W} macro where you want the document
list to appear in the message, as in the following example:
Hello {F}!
<blank line>
The document {D} does not exist! Check the spelling of
your request message against the following list of
documents:
<blank line>
{W}
More Control of your Overall Setup U-30
InfoMail/386 1.20 User Guide
Note the inclusion of the {D} macro to represent the document
the user tried to access, rather than the name of any particular
document in existence (or the name of the document list response
itself). If you want to include subject lines in the document
list, use the {X} macro instead of the {W} macro. This list
could become rather large, so it may be a good idea to stick to
the {W} macro for this standard response, and use the {X} macro
in an actual list document which has to be specially requested,
as mentioned in section 3.2.4.
If you have such a special document containing a document list,
you can omit the document list macro altogether from the
'document list' response, and simply direct the user to that
specialised list document. This is more econimical for systems
with a large number of documents, and/or a large number of
erroneous document requests.
The value of the following {C} macro is zero in a document list
response, and the {O} (filename) macro is blank. The {S}
(subject) macro in such a response is 'Failed document
request/update'. Other macros retain their usual values.
4.5.2. Customising the Document Search Results
The document search facility allows users to post a message to
InfoMail asking for a list of documents which contain a certain
word in the document tag or the document subject. The format of
an inbound search message is as follows:
================================================================
By: <user name>, <user address>
To: InfoMail Search, 2:2502/666
Re: <searchword>
----------------------------------------------------------------
<document body ignored>
================================================================
The name 'InfoMail Search' is configurable using the 'search'
field in the configuration editor. If the <searchword> contains
a space, anything after the space is ignored. The default
search response includes a brief introductory 'your search
produced the following documents' type message, and a list of
documents in {W} format.
You can specify an alternative file using the 'Results' field in
the configuration editor. If you use this file for its normal
purpose, then you must include either a {W} or an {X} macro
somewhere in the text file, wherever you want the list of
documents to appear. These macros have a slightly altered
meaning in this type of output message: the format of the list
is the same, but the list will contain only matching entries,
rather than a list of all documents.
More Control of your Overall Setup U-31
InfoMail/386 1.20 User Guide
If you wish for some reason to disable searching, you could
specify a text file which contains a brief explanation message
along the lines of 'sorry, the document search facility is not
available here', which does not include the {W} or {X} macro.
In a document search response message, the {D} macro expands to
match the search criteria, and the {C} macro expands to the
number of matching documents found. The {O} macro stays blank,
and the {S} macro expands to 'Document Search Results'.
4.5.3. Customising the Other Responses
Since all the other responses refer to some activity based
around a single document file, there is nothing special to
consider about the expansion of the macros, with the exception
of the subject {S} macro. This will contain a suitable summary
of the purpose of the message, as follows:
File Err Document file not found
Inactive Inactive document
Accept Document update accepted
Reject Document update/request rejected
All other document-related macros ({D}, {O} and {C}) contain the
correct information as read from the document record. So, for
instance, the 'File Err' message posted when a document file is
missing could contain the text
Please inform the sysop that the file {O} is missing
in which case a concientious user could give the sysop all the
information needed to correct the situation.
4.6. Inactivating the Setup
As with the task of temporarily deactivating a document, it may
be desirable to temporarily take the entire InfoMail setup
off-line. The 'Active' field in the configuration editor allows
you to do this; set it to 'No' in order to take InfoMail
off-line. All InfoMail processes will function except the
netmail scan; running INFOMAIL SCAN with the 'Active' field set
to no will cause the program to halt immediately after the
'Centurion InfoMail' banner has been displayed.
Using this option to take the program off-line prevents the need
for hunting down all calls to INFOMAIL.EXE in your batch files
or anywhere else you may call the program.
More Control of your Overall Setup U-32
InfoMail/386 1.20 User Guide
5. CONCLUSION
In the unlikely event that you have followed this user guide
from beginning to end, you should have a thorough understanding
of how to use the InfoMail program to its full potential, as
every aspect of the program has been covered in the tutorial.
Other useful documents include the Reference Guide, which you
can use to find out the use of the individual configuration
settings, document details, macros, program components and the
command line. There is also a Developer's Guide, for people who
may want to write programs to interface with InfoMail. There is
an Index which directs you to specific pages in these three
document files, and an overall Contents table containing the
contents of all the document files (and their filenames). With
all this documentation, there's no excuse for not R'ing TFM...
It is hoped that you will find InfoMail useful. As mentioned
earlier in the document, the author would appreciate a netmail
from you, saying what you think of the program, and what uses
you have found for it.
Suggestions for improvement are also welcome; indeed, several of
the improvements built into InfoMail since version 1.10 have
been things which the author would not have thought to include
himself.
Version 1.00 has attracted interest around the world, despite
the fact that other document servers had already been written.
The improvements in version 1.10/1.11 attracted more people to
this easy way of distributing information to interested parties,
and hopefully this latest version will be just as well received
as the other versions were.
Although I cannot guarantee that a future version of InfoMail
will be released, your ideas for new features will be welcome.
Enjoy!
Damian Walker, Centurion (2:2502/666), October 1996.
Conclusion U-33